Developer CD Series 1996 February: Tool Chest

home *** CD-ROM | disk | FTP | other *** search

/ Developer CD Series 1996 February: Tool Chest / Apple Developer CD Series Tool Chest February 1996 (Apple Computer)(1996).iso / Tool Chest / Testing & Debugging / Virtual User tools / VU Libraries / Controls.lib v3.0.15 & ref / Controls.lib Reference next >

Wrap

Text File | 1993-09-17 | 62.7 KB | 1,594 lines | [TEXT/MPS ]

Select the following 2 lines and hit the <enter> key before printing: Set Font Monaco; Set Size 9; Set Tabs 4; Set PrintOptions '-hf Monaco -hs 9 -title "Controls.lib Reference" -b -f Monaco -s 9 -ff "!NewPage"' TABLE OF CONTENTS Content Page -------------------------------------- Set-Up 3 Application Verification 4 Macsbug Macros 4 VUMark 1.0 5 Initialization Tasks InitControlGlobals() 6 PrintGlobals() 6 Logging Tasks LogStr() 7 TargetInfo() 7 MatchApp() 8 Keyboard Tasks TypeStr() 8 TypeList() 9 KeyEq() 9 SpecialKey() 10 Control Tasks SelectMenuItem() 10 FindMenu() 10 SelectButton() 11 SelectRadioButton() 11 SelectCheckBox() 11 CheckYesNo() 11 Window Tasks DialogCheck() 12 FindWindow() 12 SelectWindow() 12 DragWindow() 13 SizeWindow() 14 ZoomWindow() 15 ScrollWindow() 15 GetVHScrollBars() 16 CloseWindow() 16 Mouse Tasks MoveRelativeToWindow() 17 MoveMouse() 18 GetXYRandom() 18 File Related Tasks NameOK() 19 OpenDoc() 20 SF_Navigate() 20 SF_Type() 20 ReplaceExist() 21 GetNewFileName() 21 !NewPage TABLE OF CONTENTS (cont) Content Page -------------------------------------- Launch Tasks Twitcher() 21 MiniLaunch() 22 LaunchTwitch() 23 PatchLaunchTwitcher() 23 String Tasks IsSubString() 24 FindPos() 24 Substring() 24 Drawing/Tool Tasks: DrawShapeFrame() 24 SelToolFromWindow() 25 SelToolFromPallette() 25 DoDraw() 25 DoText() 26 Misc Tasks PageSetup() 27 Printer() 27 IsNumber() 27 PtInRect() 27 CenterOfScreenClick() 28 RemoveItem() 28 ReplaceItem() 28 Timer() 28 ETime() 29 DoSpecialTest() 29 Scrapbook() 29 Quit() 30 Copyright Apple Computer, Inc. 1985-1990 All rights reserved !NewPage Set-Up Hardware Requirements: Virtual User requires at least two Macintosh CPUs; 1 host and 1 target connected by LocalTalk cabling. Software Requirements: Target CPU - The target CPU must have the Agent VU init, which is included with Virtual User, installed. To do this, place the Agent VU extension(INIT) into the System Folder of the target machine. Before rebooting the machine, set the target's name by way of the Chooser (the target's name is the same as the user name). Under System 7.0 use the Network Setup CDEV. Each target must have a unique name. The target machine should be in the same state as it will be when the script is executed (i.e. if the script will test Microsoft Word™, then Microsoft Word™ should be up and running on the target machine before attempting to execute the script, unless you are using the LaunchTwitch task, in which case MiniLauncher (which can be found on the Developer CD series) should be running if under System 6.0.x, or, if under 7.0, then the alias for the application must be in place). The keyboard repeat rate should be turned off. Do this by opening the Keyboard CDEV and select OFF on the 'Delay Until Repeat' radio button cluster. Host CPU - Install the VU tool according to the instructions in the Virtual User General Reference. Running Your Script: 1) Make sure the hardware and software configurations match those explained above. 2) Launch the MPW shell. 3) From your MPW worksheet, type the appropriate command line in the following format: VU -t '*:<Target Name>' -s 'HD:Folder:<Script Name>' where <Target Name> is the user name in the Chooser of the target machine, and <Script Name> is the name of the script file to be executed. To execute the script, place the I-beam cursor in the command line and press the <Enter> key. To abort the script, type Command-Period. Make sure that you include the 2 lines: Libraries "Controls.lib"; InitControlGlobals(); at the top of your script if it uses any of the tasks from Controls.lib library. NOTE: VU Recorder can be helpful in verifying that your targets are up and responding as expected. Merely launch VU Recorder and click in the Zones list to see all available targets. !NewPage Application Verification I developed an application verification scheme that allows recogniton of a crashed target. The verification scheme uses two library tasks: LogStr(), and MatchApp(). For details on how to implement application verification please read the following: The default setting for the errorCheck parameter of LogStr(str, errorCheck:=0) is 0, therefore, using the default means that application verification is not performed. Application verifi- cation can be enabled by passing a 1 in for the errorCheck para- meter, or, since LogStr() is used for all error/status reporting the default setting of the errorCheck parameter can be changed to 1 (so that you don't have to pass the extra parameter). This is the ONLY change that you should make to the library. The next thing to do is to call MatchApp(), which will match the current application and put its title in a global (AppTitle). When LogStr() is called with errorCheck set to 1, it will compare the global Apptitle to the current application and abort if they don't match. It is important to call MatchApp after switching applications, but before you make a call to LogStr() so Apptitle can be updated. You must perform this when you open DAs as well, since the active application becomes the DA Handler. A new task called Quit() has been added. Please use this to quit an application from within a script. This assures proper handling of the Application Verification scheme. Macsbug Macros We have two MacsBug macros defined on the target machines: 'FirstTime' and 'EveryTime'. The FirstTime macro just executes a 'G;'. The EveryTime macro logs various bug information to a logfile when the target machine crashes and then reboots the target so it is ready for the next script. This is useful if you are running several scripts against a target(s). Our scripts will recognize a crash and abort that particular target's script, if the above application verification scheme is implemented. This abort is necessary when VU re-acquires the target after it has rebooted. If VU acquires the target without aborting the interrupted script, it will continue executing the script where it crashed. However, the target is now in the Finder and not the application that it was supposed to be running. This could be detrimental. !NewPage VUMark 1.0 - by NJV - Apple Computer. Description: VUMark is a MPW Script that will mark a file's VU tasks by searching the requested file for the literal string "Task" at the beginning of a line and then marking that location with the task name (the word following the 'task' string). Once the end of the file is reached, the file will be saved and, if the -nc parameter is not present, closed. Usage: VUMark [-nc] "vuScriptName" -nc - Optional parameter - if present, VUMark will not close (nc) the script after marking it. vuScriptName - The name of the VU script to be marked Usage Examples: VUMark "myScript.vu" # mark VU tasks in myScript.vu and close # myScript.vu when done VUMark -nc "myScript.vu" # mark VU tasks in myScript.vu and don't # close myScript.vu when done To install VUMark into an MPW Menu, add the following line to your UserStartup file, and make sure that VUMark is in your MPW Scripts folder: AddMenu Special "VUMark Active" 'VUMark -nc "{Active}"' !NewPage #Initialization Tasks ######################################################################### # InitControlGlobals() #======================================================================== # Author: NJV # Description: Initializes all global variables used by the Controls.lib # library. This task should be called immediately after # the "Libaries 'Control.lib';" line in the script. It # is OK to modify the values of some of the variables. This is # how you customize your VU scripting environment and the way # that your scripts will react using this library. # Parameters: None # Returns: Nothing # Examples: InitControlGlobals(); # Assumptions: That you understand what the global does before resetting it. ################################################################################ # Example Call # Example Output InitControlGlobals(); # Initializing Globals in Controls.lib 3.0.14 # (as well as output from PrintGlobals();) ######################################################################### # PrintGlobals() #======================================================================== # Author: NJV # Description: Prints the values of all Control Globals # Parameters: None # Returns: Nothing # Examples: PrintGlobals(); # Assumptions: None ######################################################################### # Example Call # Example Output PrintGlobals(); # All logging is enabled # The 'Application Verification' scheme is turned - ON # # The global 'TargetCheck' is set to output - the # title of the target's current 'Application' # # Integration Testing is - 'OFF' # The current system is - '7.0.1' !NewPage #Logging Tasks ######################################################################### # LogStr(str, errorCheck,doTargetCheck) #======================================================================== # Author: KTA # Description: Match the target and print it with whatever is passed # to it in the 'str' parameter. Set the appropriate # LogPriority based on the context of the string. # Parameters: str - string to be printed # LogPriority - The priority of the string to be printed # 0 - No logging # 1 - Errors # 2 - Comments and Notes # 3 - Summary information # 4 - More detailed # 5 - Detailed description # Returns: Nothing # Examples: LogStr("It worked"); # LogStr("It worked",3); # Assumptions: None ######################################################################### # Example Calls #Example Output LogStr("Pressed ReturnKey"); #1 - Pressed ReturnKey (Target - Title:"Se30") ######################################################################### # TargetInfo(theList) #======================================================================== # Author: NJV/KTA # Description: Match whatever is specified in global TargetInfoDescriptor # and will return the appropriate string. # Parameters: theList[1] - what to match for - default 'Target' # theList[2] - Specifier of what info to return # If theList[1] = 'Target'then # if theList[2] = # 1 - Return Title for target # 2 - Returns Application running on Target # Returns: Str # Examples: global TargetCheck := 1; # global TargetCheck :={1,2}; ######################################################################### # Example Calls # Example Output str := TargetInfo({'Target',1}); # str = "(Target - Title:"Se30")" !NewPage ######################################################################### # MatchApp(logMe,UpdateAppTitle) #======================================================================== # Author: KTA # Description: This routine will match the current Application and, # if the logMe parameter is 1, will log the current # application name by passing it to LogStr(). If a # parameter is not passed, the default behavior will # log the application's title. This routine will also # set the global AppTitle to the application's title. # Output appears in the following format: # The current application is "Finder" # Parameters: logMe - 1 to print the current application's title # 0 not to print the application's title # UpdateAppTitle - 1 to update the global AppTitle # - 0 not to update global AppTitle # Return Value: string holding current application's title # Examples: MatchApp(); # Assumptions: there is an active application ######################################################################### # Example Calls MatchApp(); #Outputs the current application's title and resets the #application global for verification.(Global Apptitle) MatchApp(0); #Does not output the current application's title, but #will reset the application global for verification. MatchApp(0,0); #Does not output the current application's title, and #will not reset the application global for verification. #Keyboard Tasks ######################################################################### # TypeStr(str) #======================================================================== # Author: KTA # Description: This routine will type whatever is passed in as the String. # Parameters: str - string to be typed # Returns: Nothing ######################################################################### # Example Call TypeStr('Hello World'); # Types 'Hello World' on the target machine and # will output what was typed. !NewPage ######################################################################### # TypeList(List,Key, flag) #======================================================================== # Author: KTA # Description: This routine will type each item in the {list} and the # selected special key after each item. If flag = 0 the # special key will be suppressed after the last item. # Parameters: List - list holding strings to type # Key - int representing key to type after the item has # been typed. # key := 0 Nothing # key := 1 (ReturnKey) # Key := 2 (TabKey) # Key := 3 (EnterKey) # Key := 4 (UpArrowKey) # flag - 1 to type special key after last item in list # 0 to disable typing of last special key # Return Value: None # Examples: TypeList({'A','list', 'of items'},2); To type each item # and then the tabKey # Assumptions: None ################################################################################ # Example Calls # Example Output TypeList({"Line 1","Line 2"},1); # Types "Line 1" and <return> key # and "Line 2" and stops with cursor # following the "Line 2" string. ######################################################################### # KeyEq(Alias,Otherkey) #======================================================================== # Author: KTA # Description: This routine will select the Keyboard Equiv <alias> # Parameters: Alias - string holding character to be typed with # command key down. # OtherKey - int representing special keys to hold down in # conjunction with the command key # 1 - Shift key # 2 - Option key # Returns: None # Examples: KeyEq("q"); ######################################################################### # Example Calls keyEq('x'); # Presses the CommandKey, types 'x', # releases the CommandKey. keyEq('v'); # Presses the CommandKey, types 'v', # releases the CommandKey. !NewPage ######################################################################### # SpecialKey(Key,keyName,n) #======================================================================== # Author: KTA # Description: This routine will type whatever SpecialKey is entered # However it will only log the name of the special character # if the special key name is also passed in as a String in # the keyName parameter. # Parameters: Key - the VU key-word for the special key to be typed # keyName - the string name of the special key # n - number of times to type the special key (default = 1) # Returns: Nothing # Examples: SpecialKey(TabKey,"TabKey"); ######################################################################### # Example Calls SpecialKey(ReturnKey); # Types the returnKey, but the output # states 'Typed some Special character' SpecialKey(ReturnKey,"ReturnKey"); # Types the returnKey, and the output # states 'Typed the ReturnKey' #Control Tasks ######################################################################## # SelectMenuItem(menuName1, menuName2, menuName3) #======================================================================= # Author: SL # Description: Selects the menu item by its name. # Parameters: menuName1 := Menu item to be selected. # menuName2 := Menu name if non-hier menu and # Level 2 menu item if hier menu. # menuName3 := "" if non-hier menu. # Menu name if hier menu. # Returns: menuTitle - MenuItem name that selection was successful # 0 - Couldn't select menu item # Notes: Do not have to pass 'menuName2' or 'menuName3' # as a parameter. In that case, default value, "", # will be used. ######################################################################## # Example Calls SelectMenuItem("Copy", "Edit"); # Selects 'Copy' from the 'Edit' menu # if it is present and enabled. SelectMenuItem("Geneva", "Font", "Format"); # Selects hierarchical menu 'Geneva' from # the 'Font 'SubMenu from the 'Format' menu ######################################################################### # FindMenu(theMenuItem) #======================================================================= # Author: KTA # Description: Returns the Menu(s) in which theMenuItem is contained. # Parameters: theMenuItem := the menuitem to be searched for. # Returns: 0 - Can't match theMenuItem. # {theMenu,""} - for a nonHierarchical menu. # {theHMenuItem, theMenu} - if its hierarchical. # Example: MyMenu := FindMenu('Paste'); ######################################################################### !NewPage ######################################################################### # SelectButton(ButtonName) #======================================================================== # Author: KTA # Description: This routine will select the button named (ButtonName) # Parameters: ButtonName - string holding name of button to select # Returns: 0 - Couldn't select button # ButtonName - Selected button OK ######################################################################### # Example Call SelectButton('OK'); # Selects Button titled 'OK' if present and enabled. ####################################################################### # SelectRadioButton(RadioButtonName) #======================================================================== # Author: KTA # Description: This routine will select RadioButton named (RadioButtonName) # Parameters: RadioButtonName - string name of radio button to select # Returns: 0 - Couldn't select radio button # RadioButtonName - Selected button OK ######################################################################### # Example Call SelectRadioButton('No'); # Selects radioButton titled 'No' # if it is present and enabled ######################################################################### # SelectCheckBox(CheckBoxName) #======================================================================== # Author: KTA # Description: This routine will select CheckBox named (CheckBoxName) # Paramters: CheckBoxName - string name of check box to select # Returns: 0 - Couldn't select check box # CheckBoxName - Selected check box OK ######################################################################### # Example Call SelectCheckBox('Left'); # Selects CheckBox titled 'Left', # if it is present and enabled. ######################################################################### # CheckYesNo(flag, DocName) #======================================================================== # Author: SL # Description: Checks for dialog boxes with "Yes" (or "OK") and "No" # buttons. If they are found, clicks one of the buttons # depending on the 'flag' parameter. # Parameters: flag - TRUE - Selects "Yes" or "OK" button. # FALSE - Selects "No" button. # DocName - Name that docment will be saved with. # Returns: What is returned by SelectButton ######################################################################### # Example Calls # Example Output CheckYesNo(); # Matches and selects either a 'Yes' or 'OK' # button or type the returnKey. If the 'Save As' # dialog appears it calls NameOK(); # and generates a file name CheckYesNo(0); # Matches and selects a 'No' button. !NewPage #Window Tasks ######################################################################## # DialogCheck(FindStaticText,CommitButton) #======================================================================= # Author: KTA # Description: This routine will to match a dialog of ordinality 1, # with StaticText - {FindStaticText}, if found it will select the # Button - {CommitButton}. # Parameters: FindStaticText - StaticText string that you want to match # CommitButton - Button to select if the static text is found. # Returns: 1 - Found FindStaticText and selected CommitButton # 0 - Couldn't find FindStaticText ######################################################################## # Example Calls # Example Output DialogCheck("Operation Failed","OK"); # if the static text "Operation # Failed" is found, prints: # "Found Dialog: 'Operation Failed'" ######################################################################### # FindWindow(specifier) #======================================================================== # Author: DM # Description: FindWindow will return the descriptor of the window # specified by the parameter specifier. # Parameters: specifier - if string, then it holds title of window # if integer, then it holds ordinality of window # Returns: 0 - Couldn't find the window # 1 - found the window OK ######################################################################### # Example Calls FindWindow(1); ######################################################################## # SelectWindow(specifier) #======================================================================= # Author: NJV # Description: This routine will select a window specified by # ordinality or title. # Parameters: specifier - holds the title or ordinality of window to # select. # Returns: 1 - Selected window OK # 0 - Couldn't find window to select ######################################################################## # Example Calls # Example Output SelectWindow(); #Selects window of ordinality 1 SelectWindow(2); #Selects window of ordinality 2 SelectWindow('Sheet'); #Selects window titled 'Sheet' !NewPage ######################################################################### # DragWindow(h,v,specifier,absolutely) #======================================================================== # Author: KTA # Description: This routine will drag the specified window # 'h' pixels horizontally (-h drags left) and 'v' pixels # vertically (-v drags up) # Parameters: h - Horizontal pixel offset to drag the window # v - Vertical pixel offset to drag the window # specifier - holds title or ordinality of window to drag # absolutely - 1 if absolute drag # 0 if relative drag # Returns: 1 - Dragged window OK # 0 - Couldn't find window to drag ######################################################################### # Example Calls DragWindow(); # Drags the first window with a grow box and a zoom # box to random coordinates (on current screen). DragWindow(200,100); # Drags the first window with a grow box and a # zoom box to the absolute coordinates (200,100) DragWindow(100,200,2); # Drags the window of ordinality 2 to absolute # coordinates of (100, 200) DragWindow(100,200,'Sheet'); # Drags the window of titled 'Sheet' to # absolute coordinates of (100, 200) DragWindow(200,100,2,0); # Selects and Drags window of ordinality 2, # 200 pixels horizontally and 100 pixels # vertically relative to its current # location. DragWindow(200,100,'Sheet',0); # Drags window titled 'Sheet', 200 pixels # horizontally and 100 pixels vertically # relative to its current location. !NewPage ######################################################################### # SizeWindow(X,Y,specifier,absolutely) #======================================================================== # Author: KTA # Description: This routine will match and resize the specified window. # If only the X and Y parameters are passed, the default # behavior will size the first window containing a grow # and zoom box absolutely. If no parameters are passed, # then the default behavior will generate random # coordinates on the main screen and resize the window # to an absolute size. If the user passes in the string # "random" for x and y and passes 0 for the absolutely # parameter (for a resize relative to current size), # then checks are performed to assure that new size will # not go off of the screen. If it does, the values will # be adjusted so that the largest the window can be sized # is to the border of the screen. # Parameters: X,Y - the Width and Height to resize the window # specifier - title or ordinality of window to be sized # absolutely - 1 if resize window absolute # 0 if resize window relative # Returns: 1 - Resized window OK # 0 - Couldn't resize window # Examples: SizeWindow(200,400); ######################################################################### # Example Calls SizeWindow(); # Sizes the first window with a grow box and a # zoom box to random coordinates (on current screen). SizeWindow(200,100); # Sizes the first window with a grow box and a # zoom box to the absolute coordinates (200,100) SizeWindow(100,200,2); # Sizes the window of ordinality 2 to absolute # coordinates of (100, 200) SizeWindow(100,200,'Sheet'); # Sizes the window of titled 'Sheet' to # absolute coordinates of (100, 200) SizeWindow(200,100,2,0); # Sizes window of ordinality 2, 200 pixels # vertically and 100 pixels horizontally # relative to its current location. SizeWindow(200,100,'Sheet',0); # Sizes window of titled 'Sheet', 200 pixels # vertically and 100 pixels horizontally # relative to its current location. !NewPage ######################################################################### # ZoomWindow(specifier) #======================================================================== # Author: KTA # Description: Selects the zoom box on the requested window. If no # parameters are passed, then the default behavior will # zoom the first window with a zoom box. # Parameters: specifier - holds title or ordinality of window to zoom # Returns: 0 - Couldn't zoom the window # 1 - Zoomed the window OK ######################################################################### # Example Calls ZoomWindow(); # Zooms the first window with a Zoom Box and a GrowBox ZoomWindow(2); # Zooms Window of ordinality 2, if it has a Zoom box ZoomWindow('Sheet'); # Zooms Window titled 'Sheet', if it has a Zoom box ######################################################################## # ScrollWindow(foo,x,y) #======================================================================= # Author: KTA/NJV # Description: This routine will scroll the specified scrollbar on # the active window. # Parameters: foo = 'H' - for horizontal scrollbar # = 'V' - for vertical scrollbar # <x><y> = the fraction x/y # Returns: 0 - Couldn't scroll the scroll bar # 1 - Scrolled the scroll bar # Examples: ScrollWindow('H',1,2) will scroll the horizontal bar 1/2 # Assumptions: That the scrollbars are present. This routine collects # only the first two scroll bars, which are assumed to be # the horizontal and vertical scroll bars. # This routine is not 100% reliable. ######################################################################### # Example Calls ScrollWindow('H', 2,3); # Collects the scroll bars and determine which # is vertical/horizontal, then scroll # the horizontal scrollbar the fraction 2/3 ScrollWindow('V', 2,3); # Collects the scroll bars and determine which # is vertical/horizontal, then scroll # the Vertical scrollbar the fraction 2/3 !NewPage ######################################################################## # GetVHScrollBars() #======================================================================= # Author: NJV # Description: This routine will return the vertical and horizontal # scroll bars. # Parameters: None # Returns: 0 - Couldn't find scroll bars # {vertical,horizontal} - list of vertical and horizontal # scroll bars # Examples: scrollBars := GetVHScrollBars(); # Assumptions: Top of vertical scroll bar is at a lower vertical value # that the horizontal (i.e. the top of vertical rect is smaller # than the top of the horizontal scroll bar's rect). ######################################################################### # Example Calls # Example Output theScrollBars := GetVHScrollBars(); # theScrollBars holds a list of the # vertical and horizontal scroll bar # descriptors, respectively ######################################################################### # CloseWindow(howClose, overwrite, specifier,DocName) #======================================================================== # Author: KTA/NJV/DMM # Description: This routine will close the specified window. If no # parameters are passed to this routine, the default behavior # will select the close box of the first window with a close box. # Parameters: howClose - 0 - tries all three ways noted below to close the # window (if needed) # 1 - tries to close window by selecting "Close" menu # item # 2 - tries to close window by typing "Close" menu # item's key equivalent # 3 - tries to close window by selecting window's # close box # overwrite - 0 - will select "No" from a save-changes dialog # if one appears when closing window # 1 - will select "Yes" to save changes # specifier - holds title or ordinality of window to close # DocName - string holding new document name - if overWrite # parameter is 1, then DocName will be used for # naming the file. # Returns: 1 - Closed window OK # 0 - Couldn't find window to close ########################################################################### # Example Calls CloseWindow(); # Selects the close box on the first window one. # It also select 'Yes' to any 'Save Changes?' dialog !NewPage ######################################################################### # MoveRelativeToWindow(x, y, specifier,mouseDown,inset) #======================================================================== # Author: NJV # Description: This routine will calculate the window's rectangle # and add x and y input parameters to the # rectangle's top-left coordinate point. It will then # move the mouse to that location. The window is # specified by the specifier input parameter. If the # specifier parameter is not present, the default # behavior will move relative to the frontmost window. # Parameters: x - int representing left (x) coord # or List of points. # y - int representing top (y) coord # specifier - holds title or ordinality of window # 0 matches first s:document c:true g:true window # mouseDown - 0 - don't hold mouse key down while moving # 1 - press mouse key down - move - release # 2 - Click after moving - no mouse down during move # x is ptList 3 - MultiDrag (pressmouse - move - move - move - release) # 4 - move - release # x is ptList 5 - MultiClick (click - move - click - move - click) # inset - inset from window rect for GetXYRandom # Returns: Nothing # Examples: MoveRelativeToWindow(12,25); # Assumptions: Assumes there is a window on the screen ######################################################################### # Example Calls MoveRelativeToWindow(100,200); # Moves (100, 200) relative to the # top left corner of the front window. MoveRelativeToWindow(100,200,2); # Moves (100, 200) relative to the # top left corner of window ordinality 2 MoveRelativeToWindow(100,200,'Sheet'); # Moves (100, 200) relative to the # top-left corner of window titled # 'Sheet' !NewPage ######################################################################### # MoveMouse(x, y, absolutely, mouseDown) #======================================================================== # Author: DMM # Description: This routine will move the mouse x,y relative to # it s current location If x and y are absent or # equal to "random", a random move is generated. # Parameters: absolutely - 1 if move absolutely, 0 if relative # x x distance to move mouse # y y distance to move mouse # if x and y are absent or := "random" then a # random move is generated # absolutely - 1 to move to absolute location # 0 to move relative to current location # mouseDown - 0 - don't hold mouse key down while moving # 1 - press mouse key down - move - release # 2 - Click after moving - no mouse down during move # 3 - press mouse key down - move - don't release # x is List 3 - MultiDrag # 4 - move - release # x is List 5 - MultiClick # Returns: Nothing ######################################################################### # Example Calls # Example Output MoveMouse(); # Moves the mouse to a random location # within the current screen MoveMouse(100,200); # Moves the mouse to absolute location (100,200) MoveMouse(100,200, 0); # Moves the mouse (100,200) relative to # its current location MoveMouse(100,200, 1, 1); # Presses the mouse button, moves the mouse to # absolute location (100,200), then releases # the mouse button. MoveMouse(100,200, 0, 1); # Presses the mouse button, move the mouse # (100,200) relative to its current location, # then release the mouse. ######################################################################## # GetXYRandom(inset, specifier) #======================================================================= # Author: SL # Description: Returns a random X and Y coordinate in the specified # screen or window. # Parameters: inset - ltrb inset from scrn or window # specifier > 0 window to find coords in # = O coords in window with s:doc g:true and c:true # < 0 coords in specified screen. Screen numbersta # is negative of specifier. # Returns: xyRandom - List of random X and Y. eg. { x, y } ######################################################################## # Example Calls GetXYRandom(); # Will return random coordinates from # the first document window with grow # and zoom box !NewPage GetXYRandom({25,25,25,25},2); # Will return random values contained # in the second window with the values # at least 25 pixels from all window # borders GetXYRandom({0,0,0,0},-2); # Will return random values contained # in the second screen ######################################################################### # NameOK(NameDoc, replaceFlag) #======================================================================== # Author: KTA # Description: This routine will type a name (NameDoc) into the text edit # field. Then it will press the ReturnKey. If there is a # document already named <NameDoc> then this task will check # the replaceFlag. If it is defined as anything but true # it will select NO to 'Replace Existing?' dialog. It will # then type the time (based on a 24 hour clock) after the # name and retype the ReturnKey. The Default is to replace # an existing document with the same name. It will also call # getNewFileName to create a file name if one is not provided. # Parameters: NameDoc - string holding the name to name the document # replaceFlag - 0 to select 'No' to 'Replace Existing' dialog # 1 to select 'Yes' to replace exisiting file. # Returns: string - filename of saved document # Examples: NameOk('Untitled1'); to name the file 'Untitled1' # Assumptions: That the SF_Put dialog is present # A call to SelectMenuItem('Save As', 'File'); should probably # be made prior to calling NameOK() ######################################################################### # Example Calls NameOk(); # Generates a new file name with a call to # GetNewFileName(). The name will be based # on the application and the current time. # If a file exists with the generated name # it will be written over. NameOk(,n); # Same as above except, if a file exists # with the generated name it will not be # written over (The time will be appended # to the end of the name) NameOk('Working Document'); # Types 'Working Document' and types the # returnKey If a file exists with the same # name it will be written over. NameOk('Working Document', false); # Same as above except, if a file exists # with the generated name it will not be # written over (The time will be # appended to the end of the name) !NewPage ######################################################################### # OpenDoc(namedoc,SelectOpen) #======================================================================== # Author: KTA # Description: This routine will select 'Open' from the 'File' menu, type # the string held in the nameDoc parameter, and # then press the returnkey. It will check to see that # the frontmost window's title contains namedoc. If not, # it assumes that the wrong file opened. It will not select # 'Open' if the SelectOpen parameter is 0. # Parameters: namedoc - string name of document to open # SelectOpen - 0 to disable selecting of the 'Open' menu item. # 1 to select 'Open' from the 'File' menu # 2 keyEq - 'o' # Returns: 1 - Document opened OK # 0 - Document not opened OK # Assumptions: Works with SF_Get, but don't have NameDoc be to long # of a string. # Examples: OpenDoc('Untit'); will select a document such as 'Untitled'. ######################################################################### # Example Calls OpenDoc('DocName'); # Selects the 'Open' menu item from the 'File' menu, # Types 'DocName' to Select the file to be opened. # Types the ReturnKey, then output the name of the # first window with a zoom box and a growbox OpenDoc(LastSavedFile); # Types the name of the last file that was # named with NameOK(); ######################################################################### # SF_Navigate(PathList, TEToggle, FinalReturn) #======================================================================== # Author: KTA # Description: Controls the navigation in Standard File. # Assigns a global SF_OriginalPath to the current directory # for return navigation. # Passes all parameters to SF_Type which performs actual navigation. # Parameters: PathList := List of directories beginning with the disk name. # TEToggle := Whether toggling from a text edit field is required # to navigate. # 1 - Toggle # 0 - No toggling required # FinalReturn := Whether to accept the final item in <Pathlist> # Returns: Pathlist ######################################################################### ######################################################################### # SF_Type(PathList, TEToggle, FinalReturn ) #======================================================================== # Author: KTA # Description: Performs navigation in Standard File. # Selects the 'DeskTop' button. Then types each item in <PathList> # folled by a returnKey. # Parameters: PathList := List of directories beginning with the disk name. # TEToggle := Whether toggling from a text edit field is required # to navigate. # 1 - Toggle # 0 - No toggling required # FinalReturn := Whether to accept the final item in <Pathlist> # Returns: Nada ######################################################################### !NewPage ######################################################################### # ReplaceExist( replaceFlag,NameDoc) #======================================================================== # Author: KTA # Description: Handles the 'Replace existing?' dialog. # Parameters: ReplaceExist := Whether to Replace a document with the same name # or generate a unique name. # 1 - Overwrite document with same name. # 0 - Do not overwrite. Generate unique name. # NameDoc := Name of file which already exists on disk. # Returns: NameDoc ( will be identical to the initial one if replaceFlag is set. ######################################################################### ######################################################################### # GetNewFileName(name) #======================================================================== # Author: SL # Description: Gets a new file name by concatenating the app name and # the current time. # Parameters: name - If this parameter is present, this routine will # only pass back the time. If this parameter is not # present, then this routine will pass back a string # consisting of the application name with the time # appended to it. # Returns: newFileName - string name for new file name # or just a time and Sec string ######################################################################### ######################################################################### # Twitcher(appName) #======================================================================== # Author: DM # Description: This task is intended to select apps from the Process List # menu in System 7.0. Use LaunchTwitch to handle launching # or twitching applications. # This routine selects apps from the Process List. # Parameters: appName - app to twitch to. # Returns: 0 if twitching to appName fails # TheCurrentApp - if twitching was successful # Examples: Twitcher("MacWrite 5.0"); # Assumptions: None ######################################################################### # Example Calls Twitcher("TeachText"); # Selects TeachText from the process list !NewPage ######################################################################### # MiniLaunch(appTitle, LaunchApp, SetDir) #======================================================================== # Author: NJV - DMM # Description: This routine will launch an application on the target # machine(s). The miniLauncher tool should be the running # application on the target machine(s). This routine will # type the input parameter appTitle to the target machine # and then type the return key (which is how an application # is launched using miniLauncher.) The application to be # launched must reside in a folder beneath the miniLauncher # tool in the directory hierarchy. For more information on # the miniLauncher tool, see the read-me that accompanies # the tool. # MiniLauncher can also open or print documents. See the # LaunchApp parameter description below for more details. # # Parameters: appTitle - title of the application or document to be launched. # The title does not have to be complete. The MiniLauncher # tool will launch the first application it finds # starting with the string appTitle. If LaunchApp # parameter is not 1, then appTitle will hold the # document name to be opened or printed. # LaunchApp - 1 to launch application # 0 to launch application via a document # -1 to print a document (launch app and print) # SetDir - 1 to set the default directory to that of the # application # 0 to bypass setting of default directory (will # end up being MiniLauncher's directory). # # Returns: 1 - Launched OK # 0 - Couldn't launch application (usually due to lack of # enough memory on the target machine). # # Examples: MiniLaunch('Word'); ######################################################################### # Example Calls MiniLaunch("TeachText"); # Launches TeachText on the target machine # and sets current working directory to # that of application MiniLaunch("TeachText Doc",0); # Launches TeachText via the "TeachText Doc" # document (TeachText is responsible for # setting current working directory !NewPage ######################################################################### # LaunchTwitch(AppName, AliasDir, LaunchApp, SetDir) #======================================================================== # Author: KTA # Description: This routine determines whether the Operating system is # 6.0x or 7.0x and launches the application accordingly. # 6.0x - Will check the Apple menu to see if the App is # currently running and select it if it is. If it is not running # it will select Mini from the Apple menu and call MiniLaunch(AppName); # 7.0x - Will check the ProcessList to see if the App is # currently running and select it if it is. if it is not it will # Select the Apple from the Apple Menu, or the <AliasDir> and then type # the <AppName> and select the Open menuItem. # Parameters: AppName - Application to be launched/Twitched # AliasDir - Folder in the Apple menu that contains <AppName>. # LaunchApp - 0 Select from Process list - Do not launch the App. # 1 Select from Process list or launch the App if # necessary. # Returns: 0 - App did not launch # 1 - App launched fine # 2 - App launched with minimum memory # Examples: LaunchTwitch('MacWrite', "#CoreAliases"); # LaunchTwitch('MacWrite Doc',"#CoreAliases",0); # Assumptions: 7.0x - That the Application (or Alias) is resident in the # Apple Menu or the <AliasDir> which contains <AppName> is. ######################################################################### # Example Calls LaunchTwitch("TeachText","Aliases"); # if 6.0.x, selects MiniLauncher # from process list and types # "TeachText" and hits <return> # if 7.0.x, selects "Aliases" # from Apple Menu, types # "TeachText" to select TeachText # alias and then selects "Open" ######################################################################### # PatchLaunchTwitcher() #======================================================================== # Author: KTA # Description: # Parameters: # Returns: # Examples: # Assumptions: ######################################################################### # write your own launching mechanisms - set global patchLaunchTwich to true !NewPage #String Tasks ######################################################################### # IsSubString(str1, str2) #======================================================================= # Author: SL # Description: Checks to see if str1 is in str2. # Parameters: str1 := Substring to be searched for. # str2 := String. # Returns: 0 := str1 is not in str2. # 1 := str1 is in str2. ######################################################################### # Example Calls reply := IsSubString("llo","Hello"); # reply = true reply := IsSubString("Hello","llo"); # reply = false ######################################################################### # FindPos(char, str, startPos) #======================================================================= # Author: SL # Description: Finds the first occurence of char in str starting # from startPos. # Parameters: char := A character to be searched for. # str := String. # startPos:= Starting position to be searched. # Returns: 0 := Char is not in str starting from # startPos. # pos := Char position of its first occurence # starting from startPos. ######################################################################### # Example Calls thePosition := FindPos("o","Foobar"); # thePosition = 2 thePosition := FindPos("o","Fubar"); # thePosition = 0 ######################################################################### # Substring(String,StartChar,NumChar) #======================================================================= # Author: PF # Description: returns the first NumChar characters of the passed String # starting at StartChar. # Parameters: String - String to use # StartChar - Character to start making substring from # NumChar - Integer number of characters to return # Returns: string # Assumptions: none ########################################################################## # Example Calls theStr := Substring("Foobar","b",2); # theStr = "ba" theStr := Substring("Foobar","F",3); # theStr = "Foo" # Drawing/Tool Tasks ######################################################################## # DrawShapeFrame(specifier := 1,ltrb) #======================================================================= # Author: DMM # Description: Click drags a rectangular frame in the specified window. # Parameters: specifier window to draw in; defaults to ordinality 1 # ltrb {"random"} or {l,t,r,b} of rect to draw # inset defines the drawing area relative to the # window rectangle # Returns: nada ######################################################################### !NewPage ######################################################################### # SelToolFromWindow(the_tool,specifier,WhichToolStr) #======================================================================== # Author: DMM # Description: This task selects tools that are embedded in document # windows # Parameters: the_tool - tool position in palette counting left to right, # top to bottom # specifier - ordinality of doc window containing tools # WhichToolStr - String name of tool # Returns: 1 - selected tool # 0 - couldn't select tool # Assumptions: Tools are selected from the front window, tool rectangles # are the same size # as a window. # Examples: SelToolFromWindow(1,2); ######################################################################### ######################################################################### # SelToolFromPallette(the_tool,specifier,WhichToolStr) #======================================================================== # Author: DMM # Description: This task selects tools from palettes that VU sees as # separate windows # Parameters: the_tool - tool position in palette counting left to right, # top to bottom # specifier - holds title or ordinality of palette window # WhichToolStr - String name of tool # Return Values: 1 - selected tool # 0 - couldn't select tool # Assumptions: Tool rectangles are the same size, VU can see the palette # as a window (tear off menus are torn off). # Examples: SelToolFromPallette(1); ######################################################################### ######################################################################### # DoDraw() #======================================================================== # Author: DM (x41220) # Description: Selects drawing tool and uses it. # Parameters: PaletteType - Type of palette # 1 - Palette is a part of document window # 2 - Palette is it's own window # Returns: Nothing # Examples: DoDraw(); # Assumptions: That the application sets up the appropriate globals # ( see SelToolFromWindow or SelToolFromPalette # Global ToolMultiplier,ToolList,Inset,Specifier,ToolRect, # ToolsAcross,ToolsDown,HeaderHeight) # if SelToolFromWindow() - HeaderHeight is not defined # if SelToolFromPalette() - ToolRect is not defined # Applications: ######################################################################### !NewPage ######################################################################### # DoText (NextLineKey, Specifier, inset) #======================================================================== # Author: ML # # Description: This routine will choose a random font size (from global fontSizeList) # and multiple random font styles (from global fontStyleList) for each of # the fonts in the global fontlist. The text defined in the global TextStr, # followed by the chosen font, size and styles will then be typed. # It will then either type the key required to move to the next line, # or move to a random position and click. # # Parameters: NextLineKey - How to move to the next line # 0 Pointer will randomly move and click # 1 Return Key - DEFAULT # 2 Enter Key # 3 Down Arrow Key # 4 Tab Key # Specifier - Use if 0 is passed to NextLineKey. Holds title or ordinality of # window to randomly move and click in. Default is "Untitled". # Inset - Use if 0 is passed to NextLineKey. Inset from window rect for # MoveRelativeToWindow. Default is {30,30,30,30}. # # Returns: none # # Examples: DoText (0) # # Assumptions: This routine cannot be used if names, sizes or styles are chosen via dialog box # (i.e. Excel). # # Your script places the cursor in the starting position where you want the first # text string to be typed before you call DoText(). If you are passing 0 to # NextLineKey (you want pointer to randomly move and click), you script must choose # the text tool, close all tool palette windows, and click in the starting position # where you want the first TextStr to be typed before you call DoText(). # # Some apps (i.e. Pagemaker and Works) use the menu item “Normal” instead of “Plain” # in describing font style. Is these cases, you must replace the correct # menuitem name with a call to ReplaceItem(). for example: # Global FontStyleList := Replaceitem('Plain', 'Normal', FontStyleList); ######################################################################### !NewPage #Misc.Tasks ######################################################################## # PageSetup( WhichDevice ) #======================================================================= # Author: KTA # Description: For PageSetup routines # Parameters: Nada # Returns: None ######################################################################## # Example Call PageSetup(); # Selects "Page Setup" from File menu and hits <return> ######################################################################## # Print() #======================================================================= # Author: KTA # Description: For Print routines # Parameters: Nada # Returns: None ######################################################################## ######################################################################### # IsNumber(whatAmI) #======================================================================== # Author: NJV # Description: This routine determine whether the input parameter is # a number or not. This could be done directly in-line, # but to avoid Developer's having to modify their code, # I updated this routine so that scripts will still work # properly unmodified. # Parameters: whatAmI - item to check # Returns: true - the parameter is a number # false - the parameter is not a number # Examples: IsNumber("Hello"); # Assumptions: None ######################################################################### # Example Calls IsNumber(2); # Returns True. The value is a number IsNumber('Hello'); # Returns False. The string is not a number ######################################################################### # PtInRect(thePoint,theRect) #======================================================================== # Author: NJV # Description: This routine determines whether or not thePoint # is contained within theRect (including borders). # Parameters: thePoint - a list of two integers # theRect - holds the coordinates of the rectangle. # Returns: true - point lies in the rectangle. # false - point does NOT lie in the rectangle. # Examples: isIt := PtInRect(thePoint,theRect). # Assumptions: None ######################################################################### # Example Calls PointIsInRect := PtInRect({2,2}, {0,0,20,20}); # Returns True PointIsInRect := PtInRect({22,22}, {0,0,20,20}); # Returns False !NewPage ######################################################################### # CenterofScreenClick() #======================================================================= # Author: KTA # Description: Clicks in the center of main screen # Parameters: none # Returns: Nada ######################################################################### # Example Call CenterOfScreenClick(); # Clicks in center of screen with Menu bar ######################################################################### # RemoveItem(Item,List) #======================================================================== # Author: KA & JM # Description: This routine was designed to remove items from lists. # Parameters: Item - Item to be removed from the list # List - any list # Returns: Newlist := if Item is removed from List # 0 := if Item is not contained in List ######################################################################### ######################################################################### # ReplaceItem(ItemtoBeReplaced, ReplaceItem, List) #======================================================================== # Author: KA # Description: This routine was designed to replace items in lists. # Parameters: ItemtoBeReplaced - Item to be replaced from the list # ReplaceItem - Item which will now be a part of the list # List - any list # Returns: Newlist := if ItemtoBeReplaced is replaced from List # 0 := if ItemtoBeReplaced is not contained in List ######################################################################### ######################################################################### # Timer(timeParam) #======================================================================= # Author: DM # Description: Calculates the time between two time descriptors # Parameters: timeParam - Specifier - what to return # 1 - return ({"{theHour}:{theSec}",theHour,theSec}); # 2 - return (("{theMonth}/{theDay}/{theYear}")) # 3 - return (theTime) - full descriptor # 4 - CurrentTime - formatted # Example: Timer(1); ######################################################################### !NewPage ######################################################################### # ETime(time1, time2) #======================================================================= # Author: DM # Description: Calculates the time between two time descriptors # Parameters: time1 - initial time # time2 - end time # Returns: "{eh}:{em}:{es}" - Difference between the two # Example: ETime(time1, time2); ######################################################################### ######################################################################### # DoSpecialTest(WhichTest) #======================================================================= # Author: KTA # Description: Hook for any special tests all the Standard QuickLooks # Call this task 3 times. # Parameters: WhichTest - Scriptor defined tests. # Returns: Whatever you want. # Example: DoSpecialTest(1); #======================================================================= # History: # KTA 9/04/90 Created ######################################################################### ######################################################################### # Scrapbook(requestElement,ccpFlag,pasteFlag) #======================================================================== # Author: KTA # Description: This routine will select the scrapbook, scroll to the # designated requestElement position, select Cut, Copy, Paste, # or Clear from the Edit menu, close the scrapbook if under System # 6.0.x, and then select Paste if the pasteFlag parameter is 1. # Parameters: requestElement - the element in the scrapbook to scroll to # ccpFlag - 1 for copy # 2 for cut # 3 for paste # 4 for clear # pasteFlag - 1 to paste after closing Scrapbook # 0 not to paste after closing Scrapbook # Returns: 0 - Couldn't complete operation # element - Scrapbook element that operation took place on # Examples: Scrapbook(2) will scroll the horizontal bar to the # second entry and then copy, close and paste. # Assumptions: That the scrollbars are present. That the string # 'Scrapbook' appear somewhere in the name ######################################################################### # Example Call Scrapbook(1,1); # Matches and selects the Scrapbook from the # Apple menu, scrolls to the first item, # selects 'Copy' from the 'Edit' menu, closes # the Scrapbook, by way of the close box, then # selects 'Paste' from the 'Edit' menu. Scrapbook(2,2,0); # Matches and selects the Scrapbook from the # Apple menu, scrolls to the second item, # selects 'Cut' from the 'Edit' menu, and closes # the Scrapbook by way of the close box. !NewPage ######################################################################### # Quit(OverWrite, DocName) #======================================================================= # Author: KTA # Description: Will turn off the Application Verification scheme, Select # the Quit menu item, check whether or not to save changes, # then reset the App verification scheme to its previous state. # Parameters: OverWrite 1 - Save changes. # 0 - Don't save changes. # DocName - The string that will be used to save the document # HowQuit 1 - Select "Quit" from File Menu # 2 - Type Cmd-Q to quit # Returns: Nada ######################################################################### # Example Calls Quit(); # Selects "Quit" from the File menu, selects "Yes" # to any "Save Changes" dialog, and selects "Yes" to # any "Replace existing" dialog Quit(0); # Selects "Quit" from the File menu and selects "No" # to any "Save Changes" dialog.